Matchwell™ User Guide

Matchwell finds duplicate photos, keeps the best copy of each, and merges what the other copies know into it: their keywords, people, captions, titles, ratings, places and more. The same print scanned twice, a photo saved again as a smaller JPEG, a copy someone emailed back to you, an edited or black and white version: Matchwell groups them and shows you each group before anything changes.

Matchwell comes two ways, with one license for both:

The Matchwell app, for Windows and Mac. It opens in your web browser and doesn't need Lightroom. It moves the extra copies to a holding folder.
The Lightroom Classic plug-in: Library > Plug-in Extras > Find duplicate photos. It merges in the catalog and flags the extra copies as rejected.

Nothing is changed until you have checked the groups and clicked Merge, nothing is ever deleted, and every run can be undone.

How alike: the five levels

Choose how alike photos must be with the How alike slider. Start at 3; move toward 1 if Matchwell groups photos that aren't copies, toward 5 if it misses copies you know are there.

Level	Finds	Good for
1. Exact copies	Files that are byte-for-byte the same	Folders copied twice, the same card imported twice
2. Same picture, saved again	The same picture at another size, in another format, or saved again with different compression	Email and web copies, a TIFF and its JPEG
3. Lightly edited (the default)	Also color, contrast or brightness changes, retouching, a slightly different crop	Most collections
4. Edited more	Also black and white versions, strong color changes, restored copies	Restoration work, family archives with many versions
5. Same shot, any version	Also very different versions of one shot	A last sweep. Check these groups: photos taken a moment apart can be grouped too

Two more choices:

Also find copies turned sideways or upside down (on by default): a scan saved the wrong way up still matches.
Deep search (off by default, slower): also finds mirrored copies (a slide scanned from the wrong side) and copies cropped much tighter than the original.
Under More: Count a camera's RAW + JPEG pair as duplicates. Off by default, so a camera's RAW file and the JPEG it saved beside it (same name, same folder) are left alone.

Matchwell reads each photo small to compare them, using a camera raw file's built-in preview, so it is quick: thousands of photos take a few minutes the first time. What it learns about each photo is remembered, so the next search of the same photos is much faster.

Which copy is kept

In each group Matchwell keeps the best copy:

the one with the most pixels;
if two are the same size, a camera raw file (or DNG) over a TIFF, a TIFF over a PNG, and those over a HEIC or JPEG;
then the larger file, then the older one.

Click Keep this one under another copy (in the app or in Lightroom) to keep it instead.

What is merged

The kept copy gets, from the other copies in its group:

the keywords and people of the others (each one is listed with a tick: untick any you don't want on the kept copy);
each field it doesn't have: title, caption, headline, rating, color label, GPS location, sublocation, city, state, country, creator, copyright date taken (when the copies differ, you choose which date the kept copy gets); the app also merges people's face areas;
the other copies' collections (Lightroom).

When two copies disagree, for example two different captions, Matchwell shows both and you choose:

the kept copy's (the default: nothing changes unless you choose);
another copy's value;
combine them: texts are joined (a caption with a blank line between), the rating is the highest, and the date is the earliest. In the app you can edit the combined text before merging.

Combine all conflicts and Keep the kept copy's values (app) set every group at once.

The app

Click Choose a folder, or paste or type a folder's path in the box under it and click Add. Add as many folders as you like. Tick Include the folders inside them for a whole tree. On Windows, the folder dialog has an address bar and a Folder box you can type into. On a Mac, press Cmd-Shift-G in the dialog to type a path.
Set How alike and click Find duplicates. A bar shows how far along it is.
Check each group. The KEEP badge marks the copy that stays; Keep this one picks another. Untick These are duplicates to leave a group alone. Below the pictures, each field shows what the kept copy will get, and each conflict lets you choose. Keywords and people from the other copies are ticked: untick any to leave it off. The With conflicts and Metadata to merge tabs show only those groups. Drag Size to make the pictures bigger; click a picture to see the copies side by side. The groups fill the window, side by side where they fit, with no scrolling: Next and Previous (or the left and right arrow keys) move to the next or previous screenful.
Click Merge and move. The kept copies get the merged metadata, then the other copies move to the holding folder: "Matchwell holding" in the first folder you chose (or one you set under What happens), keeping their folder structure, with a Matchwell report.csv listing every group. Matchwell never looks inside its holding folder when it searches.
Look over the holding folder (Open the holding folder), and delete it yourself when you are sure. Changed your mind? Click Undo this run right away, or later choose Menu > Undo an earlier run.

To merge nothing and only move the copies, untick Merge the metadata of the copies under What happens.

Camera raw files are never written to: their merged metadata goes into an .xmp sidecar beside them, as Lightroom and other programs expect.

The Lightroom Classic plug-in

Library > Plug-in Extras > Find duplicate photos.
Choose where to look: the selected photos, the folders or collections shown now (with the folders inside them), or the whole catalog. Set How alike and click Find duplicates.
Check the groups: each screen shows as many as fit on your screen, with no scrolling; > and < (or Next and Previous) move to the next or previous screenful, and your choices on every screen are kept. Untick These are duplicates to leave a group alone, click Keep this one under another copy, untick any keyword or person you don't want on the kept copy, settle each conflict, and pick the Date taken the kept copy gets where the copies differ (each date is listed with a button beside it). Larger and Smaller change the size of the pictures; More per screen and Fewer per screen change how many groups each screen holds, and Matchwell remembers your choice.
Click Merge. In Lightroom's catalog, each kept copy gets the keywords left ticked and the merged details and the other copies' collections. The other copies are flagged as rejected, get the keyword Matchwell > Duplicate, and are put in the collection Matchwell > Duplicates with the date and time. The kept copies get the keyword Matchwell > Kept copy. These keywords are never exported.
Look the extra copies over in that collection. When you are sure, Photo > Delete Rejected Photos removes them from the catalog (Lightroom then asks whether to delete the files from the disk too).

The plug-in works in Lightroom's catalog, so nothing in your files changes, with one exception: Date taken. Lightroom doesn't let plug-ins set it, so when you choose another copy's date, Matchwell has Lightroom save the kept copy's metadata to its file (Metadata > Save Metadata to Files), writes the date into the file (or its .xmp sidecar for camera raw), and has Lightroom read it back (Metadata > Read Metadata from Files). On a Mac, macOS asks once to let Lightroom control the computer (System Settings > Privacy & Security > Accessibility). If Lightroom's menu can't be used, nothing is written and Matchwell lists the dates so you can set them with Metadata > Edit Capture Time.

To put everything back: Library > Plug-in Extras > Undo a Matchwell merge.

Continue a review later

Your review is saved as you go, so a big batch can be spread over several sittings. Close the review part way (or click Merge before you have looked at every group, and choose to merge only the ones you looked at), and the next time you start Matchwell it offers to Continue where you left off, with your choices kept.

In Lightroom, each catalog has its own saved review: Find duplicate photos asks whether to continue it or start a new scan.
In the app, each set of folders has its own: the start screen lists them under Continue a review. Forget it removes one (nothing else changes).
If a photo has changed or gone since the scan, its group is ticked off and marked, so you can check it before merging.

The review also shows how long the scan took (the scan time), step by step. A deep search over a network drive (a NAS) reads each photo only once and a few at a time, which is much faster on spinning disks.

Undo

Every run keeps an undo file in your PictureOrg folder ("Matchwell-undo"). In the app, undo moves every copy back to where it was and puts back the kept copy's old metadata (any sidecar Matchwell made is removed). In Lightroom, undo puts back the kept copies' old fields, keywords, collections and Date taken, unflags the other copies and removes the run's collection. Runs made in the app are undone in the app, and runs made in Lightroom in Lightroom.

Updates

Automatic check: once a day Matchwell looks up the current version number on thepictureorg.com's download service, in the background when Lightroom starts and when you run it. Only that small version list is fetched: nothing about your computer, your photos or your license key is sent.
When a new version is out: the next time you run Matchwell, a message says so once per Lightroom session: Install now (or Download), Not now (asks again next time you start Lightroom) and Skip this version (stays quiet until a later version comes out). Nothing is downloaded or installed until you click.
Install now: Matchwell downloads the update, checks that it arrived whole and unchanged, that it carries The Picture Org's release signature and that it is newer than the version you have, and installs it into its own folder, with a progress bar. Then quit and restart Lightroom Classic to start using it. If anything goes wrong, every file is put back as it was.
Download: opens the installer download in your browser; close Lightroom Classic and run the new Setup program (Windows) or Install Matchwell (Mac). Your settings and license key are kept either way.
Plug-in Manager > Updates: shows your version and whether a newer one is out, with Check now, Install update, Download installer and What's new. Untick Check for updates automatically to turn the daily check off; Check now still works. When an update can't be installed from inside your version, the panel says to use Download installer for that one.
The app checks once a day when it opens, and Check for updates checks at any time. When a new version is out, a bar lets you install it (the app installs it into its own folder, then restarts itself), download the installer, or see what's new. The plug-in and the app update separately: each installed copy has its own files.

Updates within the major version are complimentary.

License and free trial

Free trial: every feature works for 21 days on each computer. The Plug-in Manager panel and the app show how many days are left, for example "Free trial: 14 days left".
After the trial: for 7 more days Matchwell still works, with a reminder. After that, finding duplicates still works, and merging needs a license key. When a license key is needed, Matchwell says "the free trial has ended" and offers Buy a license and Enter key....
Buying: click Buy a license in the License section of File > Plug-in Manager (select Matchwell), or on the license line at the top of the app, or go to thepictureorg.com/tools. One license is for one person on up to 2 computers, covers the app and the Lightroom plug-in, and includes complimentary updates within the major version (a version 1 key works for every 1.x release).
Entering your key: paste the whole key from your order email into the License key box in the Plug-in Manager and click Enter key, or click the license line at the top of the app. Spaces and line breaks don't matter. It then says "Licensed to" and your name. The key is checked on this computer: nothing is sent anywhere, and no internet connection is needed.
Plug-in and app: one license, one free trial. The plug-in and the app share the key and the 21-day count on each computer, so a key entered in either unlocks both.
New computer: click Remove license from this computer on the old one (it asks first), then enter the key on the new one.
Where the key is kept: in your user account, not in the program's folder, so it stays through updates and reinstalling: %LOCALAPPDATA%\PictureOrg on Windows, ~/Library/Application Support/PictureOrg on a Mac.

Help

Check my setup (in the app's menu, or in File > Plug-in Manager with Matchwell selected) checks that everything Matchwell needs works on this computer, and shows the result as text you can copy or save.
Create an error log (in the app's menu, or Library > Plug-in Extras > Matchwell: Create an error log) saves a text file on your Desktop with what Matchwell did. Email it to The Picture Org with a few words about what went wrong. File names are in it; your photos aren't, and nothing is sent by itself.

Matchwell uses ExifTool by Phil Harvey to read and write metadata, OpenCV and NumPy to compare pictures, and LibRaw (rawpy) to read camera raw previews. See NOTICE.txt.